created: 2025-04-05
Better Callouts Documentation - v0.0.1
Version: 0.0.1 (Pre-release)
This version may be unstable!
Better Callouts is an Obsidian plugin that
lets you create, edit, and manage custom callout styles
visually — no CSS[1]
knowledge needed. It handles everything for you,
including automatic snippet generation.
Features
- Visual editor for creating custom callouts
- Custom color, text color, and optional border for the callouts (no icons)
-
Automatically generates Obsidian
CSS snippets -
Automatically keeps
.obsidian/snippets/betterCallouts.cssup to date - Easy inserting the custom callouts into your notes
Getting started
1. Enabling the Plugin
-
Go to the plugin folder of your vault:
.obsidian/plugins/(if it doesnt exist yet create the folder) -
create a folder called
better-callouts -
Grab the
main.jsand themanifest.jsonfile and save them to your folder. -
Enable the plugin in Settings → Community Plugins
-
Add a new Callout (this makes the plugin add everything to the
CSS-File) -
Go to Settings → Appearance Scroll down to CSS-Snippets
-
Enable
BetterCallouts(This applies all styles created by the plugin to your notes)
If you use Obsidian Publish[2]:
-
Add the changes from the
.obsidian/snippets/betterCallouts.cssto yourpublish.cssfile for them to work on the published Obsidian -
I recommend setting up a file watcher that watches
the
.obsidian/snippets/folder and runs a shell script to merge the files into yourpublish.csswhen detecting changes
2. Plugin Settings & Creation
Settings Page
You can reach the plugins settings page by going
to the Community plugins list in
the Settings and opening
Better Callouts.
Alternatively you can open the command palette
with CTRL/CMD +
P and searching for
Better Callouts: Manage Callouts.
The settings page should look like this:
Creating a Callout
- Go to Settings → Better Callouts
- Click the + button to add a new callout
-
A callout with the name
c-newappears -
Fill out the following fields:
- Label: Name of the callout (e.g. "Warning") [3]
- Color: Background color
- Text: Text color
- Border: (optional) Add a left border
- Border Color: (only if Border is set to yes) Add a color for the border
- The callout preview will update in real time.
- Your callout will be saved automatically and added to the generated CSS snippet.
Accepted Colors
The colors accepted by the plugin are:
-
Named colors (e.g.
red,blue,darkgreen) -
HEX values (e.g.
#ffcc00,#123456) -
RGB and RGBA (e.g.
rgb(255, 0, 0),rgba(0, 128, 255, 0.2)) -
HSL and HSLA (e.g.
hsl(200, 100%, 50%),hsla(0, 100%, 50%, 0.5)) -
Obsidian variables (e.g.
var(--text-accent),var(--color-base-40))
If you're curious about the accepted colors:
- have a look here for standard css colors: CSS Colors
- have a look here for Obsidian colors: Obsidian Colors
To help you get started the plugin adds 3 default callouts with color values applied:
-
c-cleanuses Obsidians color-variables -
c-primaryuses an RGBA color, sets Text to black (#000000) and has a border -
c-accentuses an HSL color and sets Text to Darkgray (#222222)
When creating a callout please check the design
for both dark and light mode.
If Obsidians font color is hard to read in
either mode you may need to set it to a specific
color value like #000000 instead of
using Obsidians var(--text-normal).
The advantage of using Obsidians
var(--text-normal) is that this
changes color depending on
light- & dark-mode. In
light mode the text has a dark, in dark mode a
light color.
The same advantage also applies to possible
background colors like
var(--color-base-30). Using
Obsidian color variables may help you design
callouts that
better fit in with the rest of
the page.
if you use something like
var(--some-var) and forget the
closing ) other callouts may
stop working.
Input validation is planned for the future
but currently not active. For now just make
sure your input is like the colors accepted
and every ( that is opened
needs to be closed.
The plugin uses
CSS variables like:
-
--callout-bg, -
--callout-title-color, -
and
--callout-border
to apply styles.
If you're using
custom CSS Styles make sure
these variables and the
CSS Styles for callouts are not
modified or they may interfere with the
plugins functionality.
Reordering Callouts
You can reorder your callouts
by simply
dragging and dropping them in
the settings view.
This affects the order in which they appear in
the modal for inserting and also how they're
saved in the CSS-File.
Just click and drag the callout title area to a new position.
3. Inserting templates
You can insert your custom callouts into your file using markdown code like this:
> [!c-my-callout] Title
> Content
The Title ([!c-my-callout]) for the
callout you want to add is displayed in the settings
screen of this plugin.
Inserting via modal
If you want an even easier way for inserting the callouts you can:
-
press
CTRL/CMD+P(to open the command palette) -
search for
Better Callouts: Insert better callout(only works when in edit mode) - select the callout you want to insert from the modal
This adds the callout with basic Text to to your
file and can then be edited by you. The inserted
callout will also look like this:
Edit mode
> [!c-my-callout] Title
> Contents
View mode
Contents
Where is everything located?
The Plugin uses the following files:
Vault
├── .obsidian
│ ├── plugins
│ │ ├── better-callouts
│ │ │ ├── data.json
│ │ │ ├── main.js
│ │ │ └── manifest.json
│ ├── snippets
│ │ ├── betterCallouts.css
Base plugin files:
plugins > better-callouts > main.js:
here is the logic for everything this plugin does
plugins > better-callouts >
manifest.json:
tells obsidian information about this plugin
Autogenerated plugin files:
plugins > better-callouts > data.json:
here are all your custom callouts stored
snippets > betterCallouts.css: this is
the automatically generated CSS-File